IDLffShape

An IDLffShape object contains geometry, connectivity and attributes for graphics primitives accessed from ESRI Shapefiles. See Overview of ESRI Shapefiles.

Superclasses

None

Creation

See IDLffShape::Init

Properties

Objects of this class have the following properties. See IDLffShape Properties for details on individual properties.

This class has the following methods:

Version History

5.4

Introduced

5.6

Added N_RECORDS, DBF_ONLY properties

Overview of ESRI Shapefiles

An ESRI Shapefile stores nontopological geometry and attribute information for the spatial features in a data set.

A Shapefile consists of a main file (.shp), an index file (.shx), and a dBASE table (.dbf). For example, the Shapefile “states” would have the following files:

Naming Conventions for a Shapefile

All the files that comprise an ESRI Shapefile must adhere to the 8.3 filename convention and must be lower case. The main file, index file, and dBASE file must all have the same prefix. The prefix must start with an alphanumeric character and can contain any alphanumeric, underscore (_), or hyphen (-). The main file suffix must use the .shp extension, the index file the .shx extension, and the dBASE table the .dbf extension.

Major Elements of a Shapefile

A Shapefile consists of the following elements that you can access through the IDLffShape class:

Entities

The geometry for a feature is stored as a shape comprising a set of vector coordinates (referred to as ‘entities’). The (non-null) entities in a Shapefile must all be of the same type. The following are the possible types for entities in a Shapefile:

Shape Type

Type Code

Point

1

PolyLine

3

Polygon

5

MultiPoint

8

PointZ

11

PolyLineZ

13

PolygonZ

15

MultiPointZ

18

PointM

21

PolyLineM

23

PolygonM

25

MultiPointM

28

MultiPatch

31

When retrieving entities using the IDLffShape::GetEntity method, an IDL structure is returned. This structure has the following fields:

Field

Data Type

Description

SHAPE_TYPE

Long integer

The entity type.

ISHAPE

Long integer

A read-only field containing the index of the specific entity within the shape object. This value is set automatically when the shape file is written.

BOUNDS

Eight-element, double-precision array

A bounding box that specifies the range limits of the entity. This eight element array contains the following information:

Index 0: X minimum value

Index 1: Y minimum value

Index 2: Z minimum value (if Z is supported by type)

Index 3: Measure minimum value (if measure is supported by entity type)

Index4: X maximum value

Index5: Y maximum value

Index6: Z maximum value (if Z is supported by the entity type)

Index7: Measure maximum value (if measure is supported by entity type)

If the entity is a point type, the values contained in the bounds array are also the values of the entity.

N_VERTICES

Long integer

The number of vertices in the entity. If this value is one and the entity is a POINT type (POINT, POINTM, POINTZ), the vertices pointer will be set to NULL and the entity value will be maintained in the BOUNDS field.

VERTICES

Pointer to Vertices array

An IDL pointer that contains the vertices of the entity. This pointer contains a double array that has one of the following formats:

[2, N]: If Z data is not present

[3, N]: If Z data is present

where N is the number of vertices. These array formats can be passed to the polygon and polyline objects of IDL Object Graphics.

This pointer will be null if the entity is a point type, with the values maintained in the BOUNDS array.

MEASURE

Pointer to Measure array

If the entity has a measure value (this is dependent on the entity type), this IDL pointer will contain a vector array of measure values. The length of this vector is N_VERTICES.

This pointer will be null if the entity is of type POINTM, with the values contained in the BOUNDS array.

N_PARTS

Long integer

If the values of the entity are separated into parts, the break points are enumerated in the parts array. This field lists the number of parts in this entity. If this value is 0, the entity is one part and the PARTS pointer will be NULL.

PARTS

Pointer to Parts array

An IDL pointer that contains an array of indices into the vertex/measure arrays. These values represent the start of each part of the entity. The index range of each entity part is defined by the following:

Start = Parts[I]

End = Parts[I+1]-1 or the end of the array

PART_TYPES

Pointer to part types

This IDL pointer is only valid for entities of type MultiPatch and defines the type of the particular part. If the entity type is not MultiPatch, part types are assumed to be type RING (SHPP_RING).

This pointer is NULL if the entity is not type MultiPatch.

ATTRIBUTES

Pointer to Attribute array

If the attributes for an entity were requested, this field contains an IDL pointer that contains a structure of attributes for the entity. For more information on this structure, see Attributes.

Attributes

A Shapefile provides the ability to associate information describing each entity (a geometric element) contained in the file. This descriptive information, called attributes, consists of a set of named data elements for each geometric entity contained in the file. The set of available attributes is the same for every entity contained in a Shapefile, with each entity having its own set of attribute values.

An attribute consist of two components:

The name consists of a 10 character string that is used to identify the data value. The data value is not limited to any specific format.

The two components that form an attribute are accessed differently using the shape object. To get the name of attributes for the specific file, the ATTRIBUTE_NAMES keyword to the IDLffShape::GetProperty method is used. This returns a string array that contains the names for the attributes defined for the file.

To get the attribute values for an entity, the IDLffShape::GetAttributes method is called or the ATTRIBUTES keyword of the IDLffShape::GetEntity method is set. In each case, the attribute values for the specified entity is returned as an anonymous IDL structure. The numeric order of the fields in the returned structure map to the numeric order of the attributes defined for the file. The actual format of the returned structure is:

ATTRIBUTE_0 : VALUE,

ATTRIBUTE_1 : VALUE,

ATTRIBUTE_2 : VALUE,

...

ATTRIBUTE_<N-1> : VALUE

To access the values in the returned structure, you can either hard code the structure field names or use the structure indexing feature of IDL.

Examples

See the following sections for examples of:

Accessing Shapefiles

The following example shows how to access data in a Shapefile. This example sets up a map to display parts of a Shapefile, opens a Shapefile, reads the entities from the Shapefile, and then plots only the state of Colorado:

PRO ex_shapefile

 

DEVICE, RETAIN=2, DECOMPOSED=0

 

!P.BACKGROUND = 255

 

; Define a color table

r = BYTARR(256) & g = BYTARR(256) & b = BYTARR(256)

r[0] = 0 & g[0] = 0 & b[0] = 0 ;Definition of black

r[1] = 100 & g[1] = 100 & b[1] = 255 ;Definition of blue

r[2] = 0 & g[2] = 255 & b[2] = 0 ;Definition of green

r[3] = 255 & g[3] = 255 & b[3] = 0 ;Definition of yellow

r[255] = 255 & g[255] = 255 & b[255] = 255 ;Definition of white

 

TVLCT, r, g, b

black = 0 & blue = 1 & green = 2 & yellow = 3 & white = 255

 

; Set up map to plot Shapefile on

MAP_SET, /ORTHO, 45, -120, /ISOTROPIC, $

   /HORIZON, E_HORIZON={FILL:1, COLOR:blue}, $

   /GRID, COLOR=black, /NOBORDER

 

; Fill the continent boundaries:

MAP_CONTINENTS, /FILL_CONTINENTS, COLOR=green

 

; Overplot coastline data:

MAP_CONTINENTS, /COASTS, COLOR=black

 

; Show national borders:

MAP_CONTINENTS, /COUNTRIES, COLOR=black

 

; Open the states Shapefile in the examples directory

myshape = OBJ_NEW('IDLffShape', FILEPATH('states.shp', $

   SUBDIR=['examples', 'data']))

 

; Get the number of entities so we can parse through them

myshape->GetProperty, N_ENTITIES=num_ent

 

; Parsing through the entities and only plotting the state of

; Colorado

FOR x=0L, (num_ent-1) DO BEGIN

   ; Get the Attributes for entity x

   attr = myshape->GetAttributes(x)

   ; See if 'Colorado' is in ATTRIBUTE_1 of the attributes for

   ; entity x

   IF attr.ATTRIBUTE_1 EQ 'Colorado' THEN BEGIN

      ; Get entity

     ent = myshape->GetEntity(x)

      ; Plot entity

      POLYFILL, (*ent.VERTICES)[0, *], (*ent.VERTICES)[1, *], $

         COLOR=yellow

      ; Clean-up of pointers

      myshape->DestroyEntity, ent

   ENDIF

ENDFOR

 

; Close the Shapefile

OBJ_DESTROY, myshape

 

END

This results in the following:

Creating New Shapefiles

To create a Shapefile, you need to create a new Shapefile object, define the entity and attributes definitions, and then add your data to the file. For example, the following program creates a new Shapefile (cities.shp), defines the entity type to be “Point”, defines 2 attributes (CITY_NAME and STATE_NAME), and then adds an entity to the new file:

PRO ex_shapefile_newfile

 

; Create the new shapefile and define the entity type to Point

mynewshape = OBJ_NEW('IDLffShape', FILEPATH('cities.shp', $

   SUBDIR=['examples', 'data']), /UPDATE, ENTITY_TYPE=1)

 

; Set the attribute definitions for the new Shapefile

mynewshape->AddAttribute, 'CITY_NAME', 7, 25, PRECISION=0

mynewshape->AddAttribute, 'STAT_NAME', 7, 25, PRECISION=0

 

; Create structure for new entity

entNew = {IDL_SHAPE_ENTITY}

 

; Define the values for the new entity

entNew.SHAPE_TYPE = 1

entNew.BOUNDS[0] = -104.87270

entNew.BOUNDS[1] = 39.768040

entNew.BOUNDS[2] = 0.00000000

entNew.BOUNDS[3] = 0.00000000

entNew.BOUNDS[4] = -104.87270

entNew.BOUNDS[5] = 39.768040

entNew.BOUNDS[6] = 0.00000000

entNew.BOUNDS[7] = 0.00000000

 

; Create structure for new attributes

attrNew = mynewshape->GetAttributes(/ATTRIBUTE_STRUCTURE)

 

; Define the values for the new attributes

attrNew.ATTRIBUTE_0 = 'Denver'

attrNew.ATTRIBUTE_1 = 'Colorado'

 

; Add the new entity to new shapefile

mynewshape->PutEntity, entNew

 

; Note that because this is a new shapefile, the index of

; the new entity is zero.

entity_index = 0

 

; Add the Colorado attributes to new shapefile.

mynewshape->SetAttributes, entity_index, attrNew

 

; Close the shapefile

OBJ_DESTROY, mynewshape

 

END

Updating Existing Shapefiles

You can modify existing Shapefiles with the following:

Note: You cannot modify existing entities.

For example, the following program adds an entity and attributes for the city of Boulder to the cities.shp file created in the previous example:

PRO ex_shapefile_modify

 

; Open the cities Shapefile

myshape = OBJ_NEW('IDLffShape', FILEPATH('cities.shp', $

   SUBDIR=['examples', 'data']), /UPDATE)

 

; Create structure for new entity

entNew = {IDL_SHAPE_ENTITY}

 

; Define the values for the new entity

entNew.SHAPE_TYPE = 1

entNew.ISHAPE = 200

entNew.BOUNDS[0] = -105.25100

entNew.BOUNDS[1] = 40.026878

entNew.BOUNDS[2] = 0.00000000

entNew.BOUNDS[3] = 0.00000000

entNew.BOUNDS[4] = -105.25100

entNew.BOUNDS[5] = 40.026878

entNew.BOUNDS[6] = 0.00000000

entNew.BOUNDS[7] = 0.00000000

entNew.N_VERTICES = 1 ; take out of example, need as workaround

 

; Create structure for new attributes

attrNew = myshape->GetAttributes(/ATTRIBUTE_STRUCTURE)

 

; Define the values for the new attributes

attrNew.ATTRIBUTE_0 = 'Boulder'

attrNew.ATTRIBUTE_1 = 'Colorado'

 

; Add the new entity to new shapefile

myshape->PutEntity, entNew

 

; Determine the zero-based index of the new entity

myshape->GetProperty, N_ENTITIES=num_entities

entity_index = num_entities-1

 

; Add the Colorado attributes to new shapefile

myshape->SetAttributes, entity_index, attrNew

 

; Close the shapefile

OBJ_DESTROY, myshape

 

END

Graphing an Updated Shapefile

The following program graphs the cities.shp file that was created and updated in the previous examples:

PRO plot_cities

 

DEVICE, RETAIN=2, DECOMPOSED=0

 

!P.BACKGROUND = 255

 

;Define a color table

r=BYTARR(256) & g = BYTARR(256) & b = BYTARR(256)

r[0] = 0 & g[0] = 0 & b[0]=0 ;Definition of black

r[1] = 100 & g[1] = 100 & b[1] = 255 ;Definition of blue

r[2] = 0 & g[2] = 255 & b[2] = 0 ;Definition of green

r[3] = 255 & g[3] = 255 & b[3] = 0 ;Definition of yellow

r[255] = 255 & g[255] = 255 & b[255] = 255 ;Definition of white

 

TVLCT, r, g, b

black = 0 & blue = 1 & green = 2 & yellow = 3 & white = 255

 

; Set up map to plot Shapefile on

MAP_SET, /ORTHO, 39, -104, SCALE=9e6, /ISOTROPIC, $

/HORIZON, E_HORIZON={FILL:1, COLOR:green}, COLOR=yellow

 

; Show state borders:

MAP_CONTINENTS, /USA, COLOR=black

 

; Open the states Shapefile in the examples directory

myshape = OBJ_NEW('IDLffShape', FILEPATH('states.shp', $

   SUBDIR=['examples', 'data']))

 

; Get the number of entities so we can parse through them

myshape->GetProperty, N_ENTITIES=num_ent

 

; Parsing through the entities and only plotting the state of

; Colorado

FOR x=1, (num_ent-1) DO BEGIN

   ; Get the Attributes for entity x

   attr = myshape->GetAttributes(x)

   ; See if 'Colorado' is in ATTRIBUTE_1 of the attributes for

   ; entity x

   IF attr.ATTRIBUTE_1 EQ 'Colorado' THEN BEGIN

      ; Get entity

      ent = myshape->GetEntity(x)

      ; Plot entity

      POLYFILL, (*ent.VERTICES)[0, *], (*ent.VERTICES)[1, *], $

         COLOR=yellow

      ; Clean-up of pointers

      myshape->DestroyEntity, ent

   ENDIF

ENDFOR

 

; Close the states Shapefile

OBJ_DESTROY, myshape

 

; Open the cities Shapefile

myshape = OBJ_NEW('IDLffShape', FILEPATH('cities.shp', $

   SUBDIR=['examples', 'data']))

 

; Get the number of entities so we can parse through them

myshape->GetProperty, N_ENTITIES=num_ent

 

; Plot the cities on the map of Colorado

FOR x=0, (num_ent-1) DO BEGIN

; Get entity

ent = myshape->GetEntity(x)

 

; Get city attribute

attr = myshape->GetAttributes(x)

 

; Plot the cities with a symbol, as well as the city name

PLOTS, ent.BOUNDS[0], ent.BOUNDS[1], PSYM=5, COLOR=black

XYOUTS, ent.BOUNDS[0] + 0.3, ent.BOUNDS[1], $

   attr.ATTRIBUTE_0, color=black

 

; Clean-up of pointers

myshape->DestroyEntity, ent

ENDFOR

 

; Close the Shapefile

OBJ_DESTROY, myshape

 

END